# Reference of `makefilet` targets and variables

## Targets

The following list of targets is not exhaustive (e.g. the detailed `clean-*` targets are omitted).
Instead the list is focused on feature-oriented targets.

See `make help` for a full list of targets available for your specific project configuration.

* `clean`: remove built files
* `dist`: build distribution targets (e.g. a Python or `deb` package)
* `dist-deb`: build `deb` packages
* `dist-python`: build Python packages
* `django-migrate`: create and apply Django migrations
* `django-translate`: translate a Django project
* `help`: show available `Makefile` targets
* `init-deb`: populate the `debian/` directory with example content
* `install`: install the project
* `install-python`: install the Python package
* `lint`: run all linter programs (check for style and other issues)
* `lint-deb`: check the style of the `deb` packages
* `lint-python`: check the style of Python files
* `lint-python-black`: check the style of Python files with `black`
* `lint-python-flake8`: check the style of Python files with `flake8`
* `lint-shell`: check the style of shell files
* `release-major`: increase the version to the next major release
* `release-minor`: increase the version to the next minor release
* `release-patch`: increase the version to the next patch release
* `release-push`: push `git` tags to the remote repository
* `release-tar`: create a release tarball
* `release-tar-sign`: create a release tarball and a hash checksum file
* `release-undo`: remove the current release commit
* `report`: create a code coverage report
* `style`: apply formatting rules (e.g. `black` for Python code)
* `style-python`: apply formatting rules for Python code
* `tags`: create a `ctags` file
* `test`: run tests
* `test-python`: run Python-based tests
* `upload`: upload distribution files (e.g. Python or `deb` packages)
* `upload-deb`: upload `deb` packages to a repository
* `upload-python`: upload Python packages to a pypi-like repository


## Variables

* all locations are relative to the directory containing the `Makefile`
* boolean variables (e.g. `DISABLE_*`) are interpreted as *true* for the value `1`


## `ACTIVATE_VIRTUALENV`
Location of the `activate` script used for entering a `virtualenv` context for Python projects.

Default: `bin/activate` below the `virtualenv`


## `BLACK_ARGS`
Arguments to be used when executing [black](https://github.com/psf/black/).

Default: empty


## `BLACK_BIN`
Command to be used for executing [black](https://github.com/psf/black/).

Default: `black`


## `BLACK_FILES`
List of files or directories to be checked by `black`.
Project files or directories should be added manually.

Default: `setup.py`


## `BUMP_VERSION_CONFIG`
Location of a [bumpversion](https://github.com/c4urself/bump2version/) configuration file.

Default: `.bumpversion.cfg`


## `BUMP_VERSION_FILES`
List of files which are expected to change during a release (i.e. all files containing the current
version string).
This automatically generated list of filenames rarely needs to be overwritten.

Default: automatically assembled list of related files 


## `BUMP_VERSION_PARSE_REGEX`
Regular expression used by [bumpversion](https://github.com/c4urself/bump2version/) for parsing a
release string.

Default: `(?P<major>\d+)\.(?P<minor>\d+)(?:\.(?P<patch>\d+))?`


## `COVERAGE_BROWSER_BIN`
Browser name to be used for automatically opening html-based coverage reports.
Set to an empty value in order to prevent the browser from being started.

Default: `xdg-open`


## `CURRENT_VERSION_FILE`
Location of the file containing the raw version string of the latest release.

Default: `VERSION`


## `DEB_DPUT_CONFIG`
Location of the `dput` configuration file used for uploading `deb` files.

Default: `~/.dput.cf`


## `DEB_RELEASE_DISTRIBUTION`
Override the default `unstable` release distribution name.
Set to an empty value in order to fall back to `debchange`'s default behavior (which is sadly
[unpredictable for Ubuntu-derived systems](https://bugs.launchpad.net/ubuntu/+source/devscripts/+bug/1655717)).

Default: `unstable`


## `DEB_UPLOAD_COMMAND`
Command to be used for uploading `deb` packages to a repository.

Default: `dput`


## `DEBIAN_PACKAGE_SUBMODULE_DIRECTORIES`
Directories which are not sourced from additional git repositories (`git submodules`).
These directories require special treatment when building a `deb` package.

Default: empty


## `DEBIAN_BUILDPACKAGE_COMMAND`
Command to be used for building `deb` packages.

This variable is commonly overwritten in CI contexts in order to skip gpg-based signatures
(e.g. `DEBIAN_BUILDPACKAGE_COMMAND = dpkg-buildpackage --unsigned-source --unsigned-changes`).

Default: `dpkg-buildpackage`


## `DEBIAN_UPLOAD_TARGET`
Hostname for uploading `deb` package files (via `upload-deb`).
This value *must* be overwritten, if the upload feature is needed.

Default: `custom`


## `DESTDIR`
Target directory for `make install`.

Default: `root`


## `DIR_BUILD`
Directory to be used as a default location for files to be built.

Default: `build`


## `DIR_DEBIAN_BUILD`
Target directory for `deb` packages being built.

Default: `build/debian`


## `DIR_DEBIAN_SIMPLIFIED_PACKAGE_FILES`
Target directory for storing built `deb` files.
The files in this directory are simplified (lacking the version number) in order to provide
predictable filenames.

Default: `build/debian/export`


## `DIR_DJANGO_LOCALES`
Target directory for locales manged in [Django](https://djangoproject.com/) projects.

Default: `locale`


## `DIR_PYPI2DEB_BUILD`
Target directory for files being built by [pypi2deb](https://github.com/p1otr/pypi2deb/).

Default: `build/pypi2deb`


## `DIR_PYTHON_BUILD`
Target directory for storing built Python packages.

Default: `build/python-lib`


## `DIR_PYTHON_COVERAGE_HTML`
Target directory for html-based coverage report.

Default: `build/coverage-html`


## `DIR_PYTHON_SETUP`
Location of the directory containing the `setup.py` for a Python package.

Default: `.`


## `DIR_RELEASE_ARCHIVES`
Target directory for storing release archives.

Default: `.`


## `DISABLE_CUSTOM_VIRTUALENV`
Do not create a `virtualenv` for the project (e.g. below `build/`).
By default a `virtualenv` is used, if a `requirements.txt` file is found.

Default: `0`


## `DISABLE_PYTHON_LINT_FLAKE8`
Disable `flake8` for the `lint-python` target (enabled by default).

Default: `0`


## `DISABLE_PYTHON_TESTS`
Disable Python-based tests.

Default: `0`


## `DISABLE_SHELL_CHECK`
Any non-empty value prevents [shellcheck](https://github.com/koalaman/shellcheck/) from being used.

Default: `0`


## `DJANGO_WANTED_LOCALES`
List of locale names (e.g. `de fr`) to be compiled.
The locales do not need to be specified, if they were compiled at least once.
In this case the set of previously built locales is used again.

Default: determined automatically, if locales already exist


## `ENABLE_PYTHON_LINT_BLACK`
Enable `black --check` for the `lint-python` target.
`black` is disabled by default, since its `--check` is not guaranteed to be stable
(not even with a given `--target-version`).
You should enable it only, if you enforce a specific version of `black` to be used.

Default: `0`


## `FLAKE8_BIN`
Command for executing [flake8](https://gitlab.com/pycqa/flake8/) checks.

Default: either `flake8` (if it exists) or `python3 -m flake8`


## `FLAKE8_FILES`
List of files or directories to be checked by `flake8`.
Project files or directories should be added manually.

Default: `setup.py`


## `LINTIAN_ARGS`
Arguments for the [lintian](https://lintian.debian.org/) tool used by `lint-deb`.

Default: empty


## `MAKEFILET_ENABLE_PYTHON`
Force Python features to be enabled, even if no `setup.py` was found
(e.g. for `virtualenv` support).

Default: empty


## `MAKEFILET_OUTPUT_SYNCHRONIZATION`
Configure `make`'s
[output synchronization](https://www.gnu.org/software/make/manual/html_node/Parallel-Output.html)
in case of parallel execution of multiple jobs (e.g. if multiple CPU cores are available).

See the [FAQ](./FAQ.md) ("Running a single target in single-job mode") for hints regarding
interactive `make` targets (e.g. running a local development webserver).

Default: `line`


## `MAX_PARALLEL_JOBS`
Number of `make` jobs to be executed in parallel.

Default: number of CPU cores


## `PO_EDITOR`
Command to be used for executing an editor for maintaining a
[gettext](https://www.gnu.org/software/gettext/) translation file ("PO file").

Set to an empty value, if you do not want to run the PO editor automatically during the
`django-translate` target.

Default: `virtaal` or `poedit` (if one of them is found)


## `PROJECT_NAME`
The project name is used for the name of files created by `makefilet` (e.g. release archives).

Default: name of the directory containing the `Makefile`


## `PYPI2DEB_PACKAGES`
Names of [pypi](https://pypi.org/) packages to be used for building simple `deb` packages.

Default: empty


## `PYPI2DEB_PYTHON_PREFIX`
Package name prefix to be used for packages generated via `pypi2deb`.

Default: `python3`


## `PYPI_UPLOAD_TARGET`
Target for uploading Python packages.

Default: `https://pypi.python.org/pypi`


## `PYTHON_BIN`
Python executable to be used.

Default: `python3`


## `PYTHON_BUILD_SYSTEM`
Build system to be used for various operations in a Python project.

Options: `setuptools` / `hatchling` / `poetry`

Default: automatically determined based on the presence of `PYTHON_SETUP_FILE` or the content of
`PYTHON_PYPROJECT_FILE`


## `PYTHON_LINT_RUNNER`
Procedure for verifying formatting issues.

Options: `hatch` / `generic`

Default: automatically determined based on the content of `PYTHON_PYPROJECT_FILE`


## `PYTHON_PYPROJECT_FILE`
[PEP-0518](https://peps.python.org/pep-0518/) defines the content of this project description file.

Default: `./pyproject.toml`

## `PYTHON_SETUP_FILE`
Location of the `setup.py`-like file for a Python project.

Default: `./setup.py`


## `PYTHON_STYLE_RUNNER`
Procedure for applying automated formatting rules issues.

Options: `hatch` / `generic`

Default: automatically determined based on the content of `PYTHON_PYPROJECT_FILE`


## `PYTHON_TEST_ARGS`
Arguments to be used when starting Python-based tests.

Default: `-m unittest discover` or `manage.py test` (for [Django](https://djangoproject.com/) projects)


## `PYTHON_TEST_RUNNER`
Runner to be used for executing tests in a Python project.

Options: `tox` / `hatch` / `poetry` / `django` / `generic`

Default: automatically determined based on the presence of `PYTHON_TOX_FILE`, the content of
`PYTHON_PYPROJECT_FILE` or other properties.


## `PYTHON_TOX_FILE`
Location of the `tox.ini` file to be used for a running tests in a Python project.

Default: `./tox.ini`


## `PYTHON_TEST_POETRY_COMMAND`
Command to be executed for running tests in a `poetry`-based Python project.

Default: `pytest`


## `PYTHON_VIRTUALENV_ENABLE`
Create a `virtualenv` for the project (e.g. below `build/`) and use it for most Python-based
operations.

This setting replaces the deprecated setting `DISABLE_CUSTOM_VIRTUALENV`.
Set `PYTHON_VIRTUALENV_ENABLE = 0` in order to disable virtual environments
(until 'DISABLE_CUSTOM_VIRTUALENV' is removed).

Default: empty


## `RELEASE_TAR_COMPRESSION_BIN`
Compression to be used for the release tarball.

Options: `bzip2` / `gzip` / `xz` / `zstd`

Default: `gzip`


## `RELEASE_TAR_HASH_FUNC`
Hash function to be used for generating the hash for a release tarball.
The name is interpreted as an executable as well as a filename extension for the signature file.

Default: `sha256sum`


## `SHELLCHECK_ARGS`
Arguments for [shellcheck](https://github.com/koalaman/shellcheck/).

Default: `-x`


## `SHELL_FILES_ALL`
Names of files to be checked via [shellcheck](https://github.com/koalaman/shellcheck/).

Default: all files below `SHELL_FILES_DIRECTORIES` containing a shell-like shebang


## `SHELL_FILES_BASH`
Names of files to be interpreted as `bash` scripts by
[shellcheck](https://github.com/koalaman/shellcheck/).

Default: automatically determined based on `SHELL_FILES_ALL`


## `SHELL_FILES_DASH`
Names of files to be interpreted as `dash` scripts by
[shellcheck](https://github.com/koalaman/shellcheck/).

Default: automatically determined based on `SHELL_FILES_ALL`


## `SHELL_FILES_DIRECTORIES`
Directory containing shell scripts, which should be scanned via
[shellcheck](https://github.com/koalaman/shellcheck/).

Default: `.`


## `SIGNATURE_EMAIL`
Set this variable in order to use a specific GPG key for signing the release tarball
(e.g. `make release-tar-sign SIGNATURE_EMAIL=author@example.org`).
The local default GPG key is used, if the variable is empty.

Default: empty


## `TAGS_FILE`
Target filename to be used for storing [Ctags](https://en.wikipedia.org/wiki/Ctags) data.

Default: `./tags`


## `TAGS_SOURCE_DIRS`
Directories containing source files to be parsed for building a `ctags` file.

Default: `src` (if it exists)


## `VIRTUALENV_CREATE_ARGUMENTS`
Arguments to be used when creating a `virtualenv`.

Default: empty


## `VIRTUALENV_PREDEPENDENCIES`
List of Python packages which are required for creating a `virtualenv`.
A helpful error message is emitted, if any of these packages are missing.

Default: `venv wheel`

## `VIRTUALENV_REQUIREMENTS_FILE`
Location of a `requirements` file for Python dependencies.

Default: `requirements.txt`
